Let's discuss tests: I understand that the return type has changed, so we need to do something like this, which, unfortunately, is hard to read/maintain.

An alternative would be to build a psycopg cursor and use it to convert SQL to str, keeping the test similar to the previous one. An example for test_treat_meta_field:

def test_treat_meta_field(document_store):
    document_store._ensure_db_setup()
    cursor = document_store._cursor

    expr = _treat_meta_field(field="meta.number", value=9)
    assert expr.as_string(cursor) == "(meta->>'number')::integer"
    ...

The only problem with this approach: the test is no longer a pure unit test since it needs a DB connection. But we keep readability. WDYT?

What about something like this:

def test_treat_meta_field():
      cast_integer = SQL("(") + SQL("meta->>") + SQLLiteral("number") + SQL(")::integer")
      no_cast_name  = SQL("meta->>") + SQLLiteral("name")
      cast_real     = SQL("(") + SQL("meta->>") + SQLLiteral("number") + SQL(")::real")
      cast_boolean  = SQL("(") + SQL("meta->>") + SQLLiteral("bool") + SQL(")::boolean")

      assert _treat_meta_field(field="meta.number", value=9) == cast_integer
      assert _treat_meta_field(field="meta.number", value=[1, 2, 3]) == cast_integer
      assert _treat_meta_field(field="meta.name", value="my_name") == no_cast_name
      assert _treat_meta_field(field="meta.name", value=["my_name"]) == no_cast_name
      assert _treat_meta_field(field="meta.number", value=1.1) == cast_real
      assert _treat_meta_field(field="meta.number", value=[1.1, 2.2]) == cast_real
      assert _treat_meta_field(field="meta.bool", value=True) == cast_boolean
      assert _treat_meta_field(field="meta.bool", value=[True, False]) == cast_boolean

it compares two Composed instances

This test remains quite understandable in any case.
test_comparison_condition_missing_operator test_logical_condition_nested is hard to read instead.

For this reason, I was advocating to resolve to string in the test.

What's your opinion?

I'm confused.

To make sure I understand your point.

You agree with the approach for the test test_treat_meta_field as is, but instead of repr() you suggest having it as a string to compare the full output - is that it?

Regarding the test_comparison_condition_missing_operator- it's not changed by this PR - but I miss what you are suggesting.

Sorry, I was pointing to the wrong test. It's test_logical_condition_nested that gets a bit hard to read.

If we want to resolve to a string for easier comparison, we can use a cursor as I proposed in #2964 (comment)

In any case, I'll leave this decision up to you.